Using triggers

Adding a trigger

The most common place to add triggers is in the UI component itself (such as a Button 3D), but you can add them to any Kanzi object.

To add a trigger:

1. In the Project create or select the object, such as a UI component, to which you want to add a trigger.
2. In the Triggers click Add and select the message type you want to intercept.
   For example, add a Click message type.
3. In the Triggers click the Add drop-down menu for your message type and select an action.
   For example, select Write Log and enter a message you want to write to the Log window when users click the objects in the UI component. You can add any number of actions. The actions are carried out in the order from the first to the last. Write Log action is useful when you want to verify that the object received the input.
   In the Preview click any object in the UI component and with every click Kanzi Studio shows in the Log window the message you entered.
4. (Optional) If you need the trigger message to continue bubbling towards the root node, in the Trigger Settings disable the Set Message Handled property.

Intercepting trigger messages

Kanzi can intercept a trigger message either at the source object of the message, or at any ancestors of the source object. This is called bubbling. After input generates a message, the message bubbles from the object that receives the input from the parent object, then to the parent's parent, and so on until it is intercepted and handled. Once a message is intercepted and handled, bubbling stops and the message stops traveling up the project tree. If none of the ancestors intercept and handle the message, the message travels all the way to the root node of the project.

You can intercept many different message types in the same object.

To intercept a message:

1. In the Project select or create the object where you want to intercept a message.
2. In the Triggers click Add and select the message type you want to intercept.
   For example, add a Click message type.
3. (Optional) In the Triggers click the Add drop-down menu for your message type and select an action.
   For example, select Write Log and enter a message you want to write to the Log window when the trigger intercepts the message.
   For each message type, you can add any number of actions that are invoked when that message is intercepted.

4. (Optional) If you need the trigger message to continue bubbling towards the root node, in the Trigger Settings disable the Set Message Handled property.

Defining which objects receive the user input

Since only one object receives the user input at a time, when creating user interfaces take special care how your application handles the user input. For example, is a click handled by the object in the front or by the one behind it.

To define how your application handles user input, use Hit Testable property. The object that is in front of the camera and has the Hit Testable property enabled, receives the click input.

For example, if you place two boxes so that BoxFront is in front of BoxRear and occludes it completely:

• BoxFront always receives the input when:
  • BoxFront Hit Testable property is enabled
  • BoxRear Hit Testable property is enabled
• BoxRear receives the input even though it is occluded by BoxFront when:
  • BoxFront Hit Testable property is disabled
  • BoxRear Hit Testable property is enabled

Setting the size of the input area

When you want to change the input area of an object use the Hit Testable Container property, which takes into consideration the layout size rather than the bounding volume of the object. Hit testing of all UI components and layers is by default based on their layout size.

To define the size of the input area, add and enable the Hit Testable Container property in the UI component. If the UI component is not a button, you also have to add and enable the Hit Testable property.

For example, if you want to set the area of a button to be larger than the mesh in the button:

1. Create a Button 3D, add and enable the Hit Testable Container property, and add an action to the Button: Click message.
2. Create a Box inside the Button 3D, and add and set the Layout Height, Layout Width, and Layout Depth properties to the area where you want your button to respond do clicks or taps.
   The Button 3D receives the click input from the area set by the Layout Height, Layout Width, and Layout Depth properties of the Box inside the Button 3D.

See also

Tutorial: Creating a button

Triggers

Open topic with navigation